Upload Operator Connect Numbers to Customer

The Upload Operator Connect Numbers to Customer request uploads a list of SBC prefixes to a target customer tenant. The customer must have provided prior consent to the operator and the consent must include the numbers of the country calling plan (as configured by the customer in their Teams admin center). All numbers that are uploaded to Live Cloud are also downloaded to the OCDialPlan on the SBC device. See also Uploading Operator Connect Numbers.

● OCDialPlan should be preconfigured on the SBC device that is designated to manage Operator Connect numbers.
● Prior to uploading numbers, you can verify whether the targeting numbers already exist on the SBC and Live Platform (see Get Dial Plan Contents for SIP Connection).
● This operation requires you to specify a calling profile, usage and number capabilities (see Microsoft Operator Connect Calling Profiles).
● Once assigned, you unassign numbers (see Unassign Numbers).

URI

Copy 

{{baseUrl}}/api/v2/oc/numbers/action/upload?msTenantId={{msTenantId}}

You can also run this request with 'v3'.

HTTP Method

POST

Request Parameters

Parameter

Type

Description

msTenantId

string

Microsoft TenantId (Azure Tenant ID of the customer).

Request Body

Parameter

Type

Description

callingProfile

string

Names of Configured Calling Profiles.

Ticket ID

Related Service Request ticket (see Managing Service Requests).

Ticket ID

Usage

string

One of the following values:

■ CallingUserAssignment: Assign regular number directly to a user.
■ FirstPartyAppAssignment: Assign Service number to an Auto-attendant or Call queue. This option can be used for uploading Toll-free numbers. For example, +18000900770. When configuring Toll-free numbers you must also configure the 'Displayed Country Code' location (see below).
■ ConferenceAssignment: Assign number to an Audio conferencing bridge.
■ ThirdPartyAppAssignment: Assign Third-party applications to users to integrate and manage external applications, such as telephony services provided by third-party operators.

Verify that the 'ThirdPartyAppAssignment' value is supported on your Microsoft tenant.

AdditionalUsage

string

Support for an Additional usage type. For example if you configure 'CallingUserAssignment' as the Usage, then you can choose 'Conference Assignment' or 'FirstPartyAppAssignment' for the Additional Usage.

Configuration of Additional usage requires workflow Version 3.

Capabilities

list

One of the following values with matching supported usages:

■ Inbound Calling:
✔ CallingUserAssignment
✔ FirstPartyAppAssignment
✔ Conference Assignment
■ Outbound Calling
✔ CallingUserAssignment
✔ FirstPartyAppAssignment
✔ Conference Assignment
■ OC Mobile
✔ CallingUserAssignment
■ Mobile
✔ CallingUserAssignment
✔ FirstPartyAppAssignment

Address

 Address for Emergency location (mandatory in the USA)

Address

Location

City of Emergency location.

Location

Country

string

The Country dialing code of the number. See Country Dialing Codes for a full list of Country Dialing codes.

A country dialing code is Mandatory when uploading a Toll-free number in a North America Numbering Plan.

Type of Service

String

One of the following values:

■ Geographic
■ Mobile
■ TollFree

workflowVersion

integer-3

Workflow version (coded value is 3).

Phone number validation rules are in accordance with E.164. The E.164 format requires the following:

■ A + sign.
■ Country calling code (international).
■ Local area code.

Local telephone number or subscriber number.

It has the following structure: [+][country code][area code][subscriber number].

Example of a number with E.164 format in the United States

Telephone number: 415 123 1234

E.164 format number: +14151231234

■ Country code: +1
■ Area code: 415
■ Subscriber number: 1231234

Valid country code, per civic address and/or contact info of the given lead. See Country Dialing Codes.

Example Request Body

Copy 
{
"callingProfile": "5f3fbb3b-df9b-483d-b294-c7eb01e22aac",
"usage": "CallingUserAssignment",
"capabilities": ["InboundCalling", "OutboundCalling"],
"phoneNumbers": ["+61395556880"],
"workflowVersion": "3",
"country": "AU"
}

You can also verify the new numbers using the Retrieve Customer Number request (see Get Operator Connect Customer Numbers).

Example Request Body-Range

Copy 
{
"callingProfile": "5f3fbb3b-df9b-483d-b294-c7eb01e22aac",
"usage": "CallingUserAssignment",
"additionalUsages": ["FirstPartyAppAssignment"],
"capabilities": ["InboundCalling", "OutboundCalling"],
"phoneNumbers": ["+97239764533","+97239764535"],
"phoneNumberRanges": [

    {

      "start": "+97239764660",

      "end": "+97239764670"

    }

  ],
"workflowVersion": 3
}

Example Response

The initial response displays the Task Id.

Parameter

Type

Description

Task Id

string

The queued task Id that is generated for this action. You must run the Task request to retrieve the status of the action. See Task Status. Note that the wup string in the prefix is unique for this endpoint.
Copy 
{
    "taskId": "wup_c14a0a55-fcc5-4598-b405-c978e7da1af4"
}

The execution of the request may take a few minutes. The status will progress from 'In Progress' to 'Completed Success'.

Copy 
{
    "id": "wup_d4b23bb0-3b8a-4966-a368-fef9667d019f",
    "status": "CompletedSuccess",
    "details": [
        "NumbersUploaded"
    ],
    "executionMessages": [
        {
            "level": "Information",
            "message": "Input is valid."
        },
        {
            "level": "Information",
            "message": "All uploaded numbers are not present in Microsoft context."
        },
        {
            "level": "Information",
            "message": "Site GRXRATNEUZMNZ found."
        },
        {
            "level": "Information",
            "message": "Number(s) accepted by Microsoft."
        },
        {
            "level": "Information",
            "message": "UploadToAccount job status: Success."
        },
        {
            "level": "Information",
            "message": "Moving on"
        },
        {
            "level": "Information",
            "message": "Telephone numbers programmed in SBC. 8"
        },
        {
            "level": "Information",
            "message": "Workflow completed."
        }
    ],
    "outputData": {
        "CreateTime": "2023-09-28T12:14:21.5111156Z",
        "CompleteTime": "2023-09-28T12:14:47.2635149Z",
        "OcUploadNumberResult": "NumbersUploaded",
        "WorkflowVersion": 3,
        "SbcIdList": [
            8
        ],
        "MsJobWhenUpdated": "2023-09-28T12:14:46.0908199+00:00",
        "MsJobId": "899c58a5-92df-4e93-a142-a35e72b7b743",
        "MsJobStatus": "Success"
    }
}

HTTP Responses

■ 200 OK

Parameter

Type

Description
id

string

Task Id

status

string

Task status is one of the following

■ In Progress
■ Completed Successful
■ Completed Failed

The cache mechanism used to Upload numbers is according to Distributed Cache.

details

string

One of the following values:

■ Numbers uploaded: Numbers uploaded successfully
■ InvalidTelephonesError: Numbers entered incorrectly
■ MsProgrammingError: Number could not be configured on Microsoft.

executionMessages

list array

This list array includes the following parameters:

■ level
■ message

level

string

One of the following values:

■ Information
■ Error

message

string

The following 'Information' messages may appear:

■ 'Input is valid': Indicates that Telephone syntax entered is valid.
■ 'Duplicates: <PhoneNumbers>': Indicates that phone number already exists in the database.
■ 'All uploaded numbers are not present in Microsoft context': Numbers have not yet been updated on Microsoft.
■ Site found: The Live Platform IP Group link between Live Platform and SBC device has been found.
■ Number(s) accepted by Microsoft: Numbers are approved by Microsoft.
■ UploadToAccount job status:
✔ In Progress
✔ Success
■ Moving on: starting processing of next number.
■ Telephone numbers programmed in SBC and in Live Cloud database': Numbers have been updated on both SBC and Live Platform.
■ Workflow completed: End of upload process.

The following 'Error' messages may appear:

■ upload telephone numbers to Microsoft: Partner '{Microsoft Tenant Id}' does not support Offer Types [Calling] in country '{Country Abbreviation Code}': Region number that you are attempting to upload is not partnered with the operator (as configured in customer Teams admin center). For example, configured regions are Australia and Canada and you are attempting to upload an Italy number.

The following are example error messages:

■ Invalid Telephones Number (in this case, the number already existed in the database):
Copy 
{
    "id": "wup_2bd5ed7d-7eb1-44b7-88cf-6be495ccd420",
    "status": "CompletedFailed",
    "details": [
        "InvalidTelephonesError"
    ],
    "executionMessages": [
        {
            "level": "Error",
            "message": "Duplicates: +97239764533"
        },
        {
            "level": "Information",
            "message": "Workflow completed."
        }
    ],
    "outputData": {
        "CreateTime": "2023-09-21T10:53:44.6292124Z",
        "CompleteTime": "2023-09-21T10:53:44.8276113Z",
        "OcUploadNumberResult": "InvalidTelephonesError",
        "WorkflowVersion": 3
    }
}
■ Invalid Telephone Number (invalid phone number syntax). See correct format described in the 'Request Body' table above:
Copy 
{
    "id": "wup_ede0a5b7-713e-4571-847a-aa02f1b1cf1d",
    "status": "CompletedFailed",
    "details": [
        "InvalidTelephonesError"
    ],
    "executionMessages": [
        {
            "level": "Error",
            "message": "Telephone number 97239764533 rejected due: Invalid format."
        },
        {
            "level": "Information",
            "message": "Workflow completed."
        }
    ],
    "outputData": {
        "CreateTime": "2023-09-21T10:48:27.3883651Z",
        "CompleteTime": "2023-09-21T10:48:30.836471Z",
        "OcUploadNumberResult": "InvalidTelephonesError",
        "WorkflowVersion": 3
    }
}
■ "message": "upload telephone numbers to Microsoft: Partner '7a4e58a1-8348-4fa5-8d36-4e19125e4ac3' does not support Offer Types [Calling] in country 'NL'. This message is displayed if you generated a consented lead and then tried to upload a number for a country that was not configured in the customer Teams admin center.
Copy 
{
    "id": "wup_7e3ca019-c34e-4ff7-883e-e592c54d2c03",
    "status": "CompletedFailed",
    "details": [
        "MsProgrammingError"
    ],
    "executionMessages": [
        {
            "level": "Information",
            "message": "Input is valid."
        },
        {
            "level": "Information",
            "message": "All uploaded numbers are not present in Microsoft context."
        },
        {
            "level": "Information",
            "message": "Site GRXRATNEUZMNZ found."
        },
        {
            "level": "Error",
            "message": "upload telephone numbers to Microsoft: Partner '7a4e58a1-8348-4fa5-8d36-4e19125e4ac3' does not support Offer Types [Calling] in country 'NL'."
        },
        {
            "level": "Information",
            "message": "Workflow completed."
        }
    ],
    "outputData": {
        "CreateTime": "2023-10-09T14:40:19.0541215Z",
        "CompleteTime": "2023-10-09T14:40:22.0420167Z",
        "OcUploadNumberResult": "MsProgrammingError",
        "WorkflowVersion": 3,
        "SbcIdList": [
            8
        ],
        "MsJobStatus": ""
    }
}

When attempting to upload a a Toll-free number with the usage "CallingUserAssignment".

Copy 
"usage": "CallingUserAssignment",
"capabilities": ["InboundCalling", "OutboundCalling"],
"phoneNumbers": ["+18000900790"],
"workflowVersion": "3",
"country": "US"
}

The following error message is displayed as Toll-free numbers must be configured with the usage 'FirstPartyAppAssignment'.

Copy 
{
    "id": "wup_d62adf69-47c6-44bb-83e0-dfc632a2eca0",
    "status": "CompletedFailed",
    "details": [
        "MsProgrammingError"
    ],
    "executionMessages": [
        {
            "level": "Information",
            "message": "Input is valid."
        },
        {
            "level": "Information",
            "message": "All uploaded numbers are not present in Microsoft context."
        },
        {
            "level": "Information",
            "message": "Site GRYXIKLDOVPLU found."
        },
        {
            "level": "Error",
            "message": "upload telephone numbers to Microsoft: Plan/Usage 'Calling User Assignment' does not support Toll Free TNs upload."
        },
        {
            "level": "Information",
            "message": "Workflow completed."
        }
    ],
    "outputData": {
        "createTime": "2024-05-07T15:02:02.8461328Z",
        "completeTime": "2024-05-07T15:02:13.3898797Z",
        "ocUploadNumberResult": "MsProgrammingError",
        "workflowVersion": 3,
        "sbcIdList": [
            8
        ],
        "msJobStatus": ""
    },
    "createTime": "0001-01-01T00:00:00"
}

The following message is displayed if there are no SBC devices assigned to the Calling Profile and therefore you cannot make or receive calls to this number.

Copy 
{
    "errors": {
        "CallingProfile": [
            "There are no SBCs assigned to this calling profile!"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-ce7db116205054eee1c59c80ebe7f48d-d5a3edc4aadfc80d-00"
}

outputData

List array

 

This array includes the following parameters:

■ CreateTime
■ CompleteTime
■ OcUploadNumberResult
■ NumbersUploaded
■ WorkflowVersion
■ SbcIdList
■ MsJobWhenUpdated
■ MsJobId
■ MsJobStatus

CreateTime

string($date-time)

Timestamp at the commencement of the number upload.

CompleteTime

string($date-time)

Timestamp at the completion of the number upload.

OcUploadNumberResult

string

One of the following values:

■ NumbersUploaded
■ InvalidTelephonesError
■ MsProgrammingError

WorkflowVersion

integer

Version of the Workflow API.

SbcIdList

integer

Id of the SBC device in the Live Cloud database.

MsJobWhenUpdated

string($date-time)

Timestamp when the Microsoft tenant platform was updated with the new number.

MsJobId

string

Id of the job to update the Microsoft platform.
■ 400 Bad Request: Syntax Error
Copy 
Number upload example:
"phoneNumbers[11]": [
"Unexpected character encountered while parsing value: ,. Path 'phoneNumbers[11]', line 6, position 183."
■ 400 Bad Request: 'Invalid Calling ProfileId'; see Retrieve Microsoft Operator Connect Calling Profiles to verify correct Calling Profile Ids).
Copy 
{
    "errors": {
        "CallingProfile": [
            "Invalid CallingProfileId!"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-b0da85edb231924dee2cf223620f3e60-e788e6802f612a84-00"
}
■ 400 Bad Request: 'No SBCs attached to Calling Profile'; see Get Calling Profiles Mapping to SBC Devices to verify which SBC devices are attached to Calling Profiles.
Copy 
{
    "errors": {
        "CallingProfile": [
            "There are no SBCs assigned to this calling profile!"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-ce7db116205054eee1c59c80ebe7f48d-d5a3edc4aadfc80d-00"
}